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A. THE PROBLEM 


There is much discussion in the software engineering 
literature concerning the ovarwhelming cost of software 
Maintenance. It has been indicatel that in some systems up 
to eighty percent of the cost of a software system is 
consumed in the maintenance phase of the software life cycle 
(Ref. 1]. IC ordet to Properly maintain thə2 software, it 
must be properly documented. Often the same person does not 
Berform tasks in ali phases cf the Life cycie, thus without 
documentation, continuity between the phases can he lost. 
Sometimes the only interface between each phase is a piece 
of documentation. eers po ካከ ተይ ከር: 514ቶዋ of docu- 
men-ation in the software lite ሮኘፎ45፤ if the documentation 
between phases is not done well, mach Ofe=h= work orn -he 


roject must be recreated for subsequent phases. 


Be PURPOSE AND APPROACH 


There is a lack cf cohesive discussion in current liter- 
ature concerning proper docunentation for efficient software 
maintenance. Because of the tremendous cost involved with 
software maintenance, an attempt to ease the maintenance 
effort needs to be made through the use of adequate 
documentation. 

The curpose of this thesis is to address documentation 
as a method of information transfer throughout the life 
cycle of a software project in the support of software main- 
tenance. Various types of documentation are discussed and 
evaluated as *o their effectiveness toward easing the main- 


tenance effort. An attempt is made to determine the proper 





type and amount of information needed to effectively main- 


tain the software project. An effort is made t5 cateqemiz= 
and quantify different aspects of documentation based cn 
task and user needs. The concept of a documentation hier- 


archy is put forth as a method for organizing these aspects. 
The idea is to give the receiver of that information 
precisely the amount of information required *o complete the 
Maintenance task. Too much information can bog one down 
With unnecessary details while too little informaticn can 
cause one to waste many hours in trying to understand the 
progran. Thus a solution to the problem of accessing the 
exact quantity of documentation is offered. 

Chapter I gives an overview of the documentation prcblen 
as it relates to software maintenante. A description of the 
approach for the thesis is given along with some general 
definiticns of terms used in the software maintenance envi- 
ronment. Also, the idea of minimal documentation is intro- 
duced in this chapter. 

Chapter If discusses software maintenanca Ine dee aca: 
with a look at the software life cycle. À software project 
Scenario is described to set basic guidelines fer the 
thesis. The differant types of maintenance as they relate 
to the software modification task are described  alona with 
the identification of some of the causes and solutions for 
the software maintenance problen. 

Chapter III introduces the ilea of the transfer of 
knowledge between individuals as being the goal of affective 
documentation. This knowledge transf2r is accomplished by 
ን 5132252407 various methods for recording >< 2۴9.۶03.776۰ 
Documentation is then categorized according to the type oz 
information that is conveyed and also according to depen- 
dencies based on a person's skill and position on the main- 
tenance tean. Finally, the role of documentation for 3 
project is discussed. 





EGET introduces the concept of a documen-ation 
Iesrarchny Ln support of minimal documentation. The levels 
of the hierarchy are based on the level of detail contaired 
in the documentation. The various users of the dccuaenta- 
tion need only to access the proper level in the docunenta- 
tion hierarchy in order to have the minimal documentation 
that is required for the completion of the task at hand. 

Chapter V discusses the effectiveness of several 
specific forms of documentation in relation to the perform 
ance of the maintenance task. The svaluation is made hat 
there is not a "best" fozm of documentation for all mainte- 
nance tasks. The most effective documentation form varies 
With the maintenance task and the type cf programming 
processing (sequential or concurrent) being used. 

Chapter VI consists of the thesis conclusions and 


recommendations. 


DEEINTTIONS‏ نر 


“er can basic definitions are needed in order to prop- 
erly address the issue of software documentation as it 
relates to software maintenance. For the purposes of this 
thesis, software maintenance will be considered to be the 
process of updating and correcting a software system once 
the project is delivered and made operational. 

Software documentation is the recorded informaticn that 
can be used to transfer information and ideas from one 
person to another. Unlike software maintenance, whick has 
been defined to begin after the project is delivered, soft- 
ware documentation is produced throughout the entire soft- 
ware life cycle from the conceptual phase to the support 
phase. Since documentation follows the evolution of a soft- 
ware systen, adequate and reliable documentation is inva- 
luable when it comes to maintaining the systen. 
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Minimal documentation is defined as the exact amount of 
documentation on a project that is required by the receiver 
to accomplish the receiver's task. When the minimal docu- 
mentation concept is used, only the precise amount of docu- 
mentation that is needed is accessed, and the receiver is 
not forced ቲጋ wade through unnecessary information. Just 
enough information is recorded so that the recsiver is able 
to proceed with the job at hand. This, then, is an idea of 
documentation efficiency with no more and no less informa- 
tion being exposed to the receiver than is actually needed. 

Meintainability is a termi that must be clarified. 
Martin and McClure {Ref. 2] define maintainability as the 
"case wit which a software system can be corrected when 
errors or deficiencies occur, and can be expanded or 
contracted to satisfy new requirements." Maintainability of 
a software system can be enhanced with the availability of 
adequate minimal documentation. 

Understandability is considered to be one of the mos: 
important concepts in the realm of maintainability. “artin 
and McCiure define understandability as "the ease with which 
we can understand the program purpose and how the program 
achieves its purpose". Since docunmzatation transfers infor- 
maticn cenceraing software system evolution, the minimal 
documentation concept aids in the achievement of program 
understandability. 
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A. THE SOFTWARE LIFE CYCLE 


The development of a software project goes through 
Several phases from conception to actual system operation. 
This development process is called th2 software life cycle. 
There are several mcdels availabl= to represent the soft- 
wars life cycle. The one used by the Department of Defense 
as indicated in Department of Defense Instruction 5000.1 is 
presented in Pigure 2.1. It gives a reasonable representa- 
tion of mos- simple models. An alvantage of this model is 
that each major phase is Broken BO Lt subsequent 
subphases. This model is general enough to be applied to 
mest software systems, with the dstails being left to the 
۶16ر ےہ5‎ 2۶63 

Documentation must be carried throughout the life cycle 
in order to promote understarndability in subsequent phases. 
Ultimately, the ideal documentation contains enough informa- 
tion such that when the program is completed and is opera- 
tional, it can be maintained effectively. 

The major problem with the Department of Defense model 
is the implication that is given concerning the flew of the 
software life cycle. One is left with the idea that as one 
phase abruptly halts, the next phase begins. Insprac-ıcee, 
the phase boundaries are somewhat obscure. Quite often work 
on one part cf a phase begins before all work in a previous 
phase is completed. Also one gets the impression that there 
are no interdependencies between the phases. In reality, 
decisions made in one phase often directly affect the work 
of a subsequent phase. This makes each phase somewhat 
dependent upon decisicns made in a previous phase. Also 
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Figure 3 Department of Defense Life Cycle Model. 
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there are tines when a decision made in one phase is 
Perermened to be unrealistic by restrictions or act 
taken in a following phase. Thersfore, a feedback mech 
ween phases in order to 


keep the scitware project developme 


2 
is needed to carry information bet 
ment moving. 

2 


Documentation is the method f recording information 
miat is to be transferred forward and backkarid to aid in 
softwar? modification. Pigure 2.2 gives a mors realisti 
view cf the software cycles indicating some of the phase 
Enterrelationships (Ref. 3]. 


Figure 2.2 shows validation ani verification subphases 


I 


m the requirements and désign phases of the cycle. This is 
important because each phase should be verified as being 
pos 

crder to avoid unnecessary work. For example, it would be 


sibie and feasible as early in the cycle as possible in 


wasteful to work through to the implementation phase only to 
SmI OU that the project was never feasible in the fírst 
place. 

Studies indicate that the most economical time to catch 
and correct a problem is as early in the development cycle 
as possible. The cost of detecting and correcting an error 
more than doubles for each phase through which it passes 
undetected. This rate of cost increase holds true for each 
Subsequent phase  thrcugh which tha problem passes without 
detection. [Ref. 3] and (Ref. 4]. 

While the sinplistic view presented in Figure 2.1 is 
relatively easy +9 comprehend, it is extremely important to 
remember the interrelationships between the various phases 
as indicated by Figure 2.2. With those interrelationships 
being kept in mind, the simplified life cycle model shown in 


Figure 2.1 will be adequate for use in this thesis. 
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Figure 2.2 The Waterfall Model of the Software Life-cycle. 
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5. THE SOFTWARE PROBLEM 


Bohem [ Ref. 3] gives us some insights into the magnitude 
of the economics involved with the software problen. The 
annual cost of software for the United States in 1980 was 
about 2 percent cf the Gross National Product. The cost is 


expected to grow faster than the general rate of th 


(D 


economy 
thus representing an even larger proportion or the Gross 
National Product as time goes on. The portion of the effort 
spent on software maintenance has increased faster than the 
effort spent on software development. و‎ ۰۴۳۳ ۴۱2۷۰ 6 of 
software maintenance taking such a large portion of the 
total cost of a system, it would be wise to find ways to 
enhance the efficiency of the maintenance effort. 

Along with the eccnomic issues of software maintenance, 
we must look at the social aspects of computers as they 
relate to software. Things such as computerized billing and 
banking have made a permanent impact upon the lives of most 
Americans. An increasing number əf workers in the United 
States will be relying on computers to perform tasks 
involved with their daily work. BV 1985S it is prədictsd 
that approximately 80 percent of ths working population will 
fall into that category. NN sS ad of c.owpürer end 
software proliferation, there will be continued growth in 
the amount cf software that is needad. This growth of soft- 
ware translates into a Significant amount of necessary 
software maintenance as both the software system and the 
state of technology change. 

As the need for software maintenance increases, Sc 
becomes imperative that maintenance efficiency be improved. 
The idea of using minimal documentation in order to improve 
understardability, which in turn aids maintainability, is 
seen as a way  *o increase the efficiency of the software 


naintenance effort. 
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1. 5ር5፻55555 


There are many types of programs that are developed 
Tanging from very small to very large, andthe size of 2 
program can determine the software documentation issues 
related to that particular progran. In order to address 
specific documentation issues we nee E0 FOCUS 3h a partic- 
ular Scenario. 

The program with which we will be concerned is one 
csNMEiIOsumn length invclvizg thirty to forty thousand lines of 
come. It is 2 software program that is to be maintained, so 
it is neccessary that software documantation be generated. 
(If a program were never to be modified, «han documenta- 
tion would not be necessary.) EOE Enon 11 መር or thus 
thesis, the program code is not considered *o be a form of 
documentation. The program is one that was developed by a 
software development team (as opposed to being developed by 
a solo progranmer) with documentation maintained throughout 
the development. The development followed the basic guide- 
lines as indicated in ths Department or Defense life cycle 
model (Figure 2.1). The program developers are not the end 
users of the system. The program is 2mbedded in an environ- 
ment that is subject to change. 

When a modification to the system is required, a 
change request DEetocol is foilowed in which a 
requested change is considered and a determination is made 
as to whether the change should be incorporated into 
the existing systen. If the change is to be made, it is 
acted upon by a designated maintenance tean. The personnel 
essigned to the maintenance team may or may not have other 
collateral duties in the organization, and they may or may 
not have had any connection with th2 original development of 
the system. Emergency changes are implemented as quickiy as 
possible while routine modificatioas are implemented in an 
annual system update. 
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The system is considered to have a ifs expsc-arcy 
EMpproximately twenty years, ani it is further assumed 


that the system has been in cp¢ration for several y 
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updated accordingly. 


2. Understandability 


Understandability is considerad to be one of the 
most important concepts in the realm of maintainability. If 
apiece of software that is to be maintained proves +o be 
oem cfriciert and successful, yet is not understandable to 
the maintainers, it can be difficult and expensive (if not 
impossible) to modify to meet changing needs. 

In a good system, there is information avaiiable as 
to the purpose cf the system, the proper uss of the systen, 
and the proper maintenance of the system (Ref. 2]. All 
phases of the life cycle will have accomparving documenta- 
tion concerning the development at 2ach stage of the system, 
ana har documentation will carry the required informa- 
Seon that aids in the understandability of the progran. 

Familiarity is a factor that helps determine the 
effectiveness and understandability of a program. A person 
who is very familiar with the cod2 and the functioning of 
the system would  prcbably not hive great difficulty in 
understanding the system, even if the documentation were 
somewhat lacking in quality and the system itself were very 
complex. On the other hand, the inexperienced or unfamiliar 
Maintainer would probably have difficulty in understanding 
the program. de will see later how the factor of famil- 
larity determines fer an individual the level of detail 
needed in the documentation. 

Martin and McClure state that understandable 
programs generally have several common characteristics: 
structuredness; consistency; complateness; conciseness; and 
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documentation. Each of these characteristics wi 
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discussed in more detail. 
a. Structuredness 


The effective structuring of a program incréases 


understanding by standardizing th program forma+. Ta 


iD 


Seamagardization will set restrictions and guidelines on the 
logical flow of the program. Program modules will be set up 
in a hierarchical manner with the order of exscution detsr- 


mined by the guidelines. Th2 use of these guidelines for 


r 
0፡1 ቤከር ርዕ“ በ የሮ ርርሮተዮተ ከ will provide a consistent logic «ha: 


ct 


will aid the understandability of the overall systen. 
be Consistency 


A program should be written ina consistent 
Style in accordance with established programming standards. 
The structureldness mentioned above can be considered +o be 2 
method orf developing a consistent styles. It is difficult to 
understand a program in which the style of writing does not 
follow a common methcd of construction. This is sometimes 
difficult to accomplish when several members work together 
as a team on a project unless close communication control is 
naintained. Consistent types of comments must be main- 
tained. When a module is describsi, it should handle the 
description of the piece of code the same way every other 
module is handled in terms of the amount of detail discussed 
and the order in which the information is provided. 
Variable names should bs selected with the same sort of 
reasoning throughout the program, and the program should be 
consistent with the design instructions. In-line comments 
shoulá be used to clarify coding statements, and this prac- 
tice should be consistent throughout the program. There 
should be no visible evidence that the program was  no- 
written by one person with a consistent train of thought 
throughout the develcpment process. 
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C. Completeness 


A complete program has all of its components 
available to use and to be perused by the maintainer. The 
maintenance person must be abl2 to access all parts of the 
program that are related to the mainterance function if 
understandability is to be accomplished. Any variables or 
modules should be included in a cross-reference scheme sc 


that the maintainer can trace a program component throughout 


the system. Every unusual feature in the program should be 
clearly explained, and error messages should be 9ں‎ 
understandable. 


d.  Conciseness 


A concise program is 5na that uses only the 
coding necessary to achieve the design requirements with no 
extra (perhaps unused) pieces of coie. Every piece of code 
must be reachable by some? action əf the progran. Unused 
variables and duplicate functions should be ronexistent and 
comments should not be excessively verbose or cryptic in 
meaning. Understandability decreases when complexity cver- 
takes simplicity. The system, though it in itself may ط٥‎ 
complex, can be Simplified through the proper use of 


conciseness principles. 


e. Document ation 


Perhaps the concept that pulls all of the above 
understandability methods together is the development (and 
use) Ct gocd documentation techniques. The use of all of 
the above ideas that promote understandability in a system 
may not in +hamselves be successful. 

The structuredness of a program must be docu- 
mented in such a way that the structurization methods are 
understood by the maintainers. Th2 consistent program nust 
have the modules described and documented in a consistent 
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way. Comments should be arranged near each module ٥م‎ 
describe the module in some detail. The module comments 
should include the purpose of the module, the variables used 


or modified in the module, ۶43۰5 0۳9 70۴760 co: the out pus 
of the module. The module description should indicate ths 


relative postion of the module with respect to other modules 
in the progran to give some idea as to how ths module was 
reached and how it fits into the program hierarchy. 

Documentation also aids unders«andability by 
eM alg “intomwation as to the completeness of the 
program. Information is recorded as to how a module of the 
program is reached and how each module is related in the 
overall system scheme. Proper documentation should also be 
concise with only the necessary information being provided 
to the maintainer so as to enhance understandability without 
comtusion. 


3. Maintenance Effo 


Since the maintenance effort represents such a large 
portion of th2 overall cost of a software system, a look at 
the software maintenance effort andi ways in which to make 
this effort efficient by means of minimal documentation is 
morder. 

A survey of data processing maintenance activities 
by Lientz and Swanscn (Ref. 5] shows that only half of 
the people who are assigned to maintain programs actually 
worked on their development. rhis fact is Significant in 
Was a lack” of continuity of the original thinking occurs. 
To make matters worse, the number of development personnel 
assigned to the maintenance effort diminishes even further 
as the life of a software system is extended. Good docu- 
mentation passes information about the program between those 
personnel developing the program and those maintaining tae 


Progzam, <hüs preserving the continuity of thought. 
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In crder to gauge the magnitude of the maintenance 
۰٦٦ء0٥7‎ and Swanson describa ¢he effort as the resul: 
Semone combination of four variables: System age; 7280 
size; relative amount of routine debugging; and the relative 


development experience of the maintenance personnel. As th 


0 


syszem age extends, tha systen size tends to increase 
leading to a greater maintenance  sffor*. With an increase 
in system size, the system tends to nead more routine debug- 
Hung again increasing the maintenance effort. When the 
System age increases, there is also an increasing amount of 
personnel turnover which leads to ‘the declining relative 
development experience of the maintainers, thus again 
causing an increase in the maintenance effort. This nainte- 
nance effort increase, of course, results in a rise of 
overall maintenance costs. 

Minimal documentation can be used as a means to 
promcte program understandability which will make the main- 
tenance effort become more efficient, and in turn cause a 


decrease in software maintenance costs. 


4. Types of Maintena 


i 
t 


Generally software maintenance can be divided into 
three categories: corrective; adaptive; and perfective 
maintenance [Ref. 6]. Corrective maintenance is considered 
to be purely the correction of software errors. Though 
corrective maintenance is traditionally seen as the most 
obvious type of maintenance task, it is interesting to note 
that the time spent solely on the correction of errors 
amounts to only seventeen to twenty-five percent of the 
maintenance person's time [ Ref. 5] and [ Ref. 7]. 

Adaptive maintenance is considered to be the process 
ef adapting or changing the software to meet the environ- 
mental constraints of the systen. An adaptive change would 


be considered to take place if a naw operating system is to 
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be installed on the computer that is used by the program 
being maintained. This area of maintenance takes up abou+ 
eighteen to twenty-five percent of the time spent on maínte- 
nance [ Ref. 7]. 

Perfective maintenance concarns the "perfecting" o£ 
the system by making user-requested changes to the software 
to make the system perform "better", It is interesting to 
note that while tha perfective maintenance activity (some- 
times called providing enhancements) does not involve the 
act of correcting errors, it takes between fifty and sixty 
percent cf the maintenarce person's time--by far the largest 
single time chunk in the software maintenance effort 
Sher. 7]. This is in contrast to what is gener 


2 
ered to be "reali" maintenance, that of the corrective type. 


5. Cause 


of Maintenance Problems 


جس جک nn‏ چیت یلا 


(ሀ) 


It iS "٦56826 ت۶2‎ 36.13” to look at some of the things 
that create the need for software naintenance and ways that 
the use of proper documentation can ease the maintenance 
task. 

Schneidewind [Ref. 8] indicates chat several items 


bring about maintenance problems. OL 5 zhe act. tha 


€ 


maintenance is often viewed by both designers and users as a 
task that is not very glamorous. This leads to a tendency 
for personnel to want only to design systems while letting 
the maintenance aspect of the system take a low priority. 
This leads to many of *he maintenance problems being ignored 
during <he development phase, including the proper documen- 
tation of the project as it progresses. Maintenance is 
often not even considered during the software development 
process. 

In reality, documentation and maintenance ideas must 
parallel system development through all of the software lifes 


cycle phases, and actually becom2 an integral part of the 
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design criteria. This is necessary if a program is to b2 
easily understood and efficiantly operated and maintained. 

Glass and Nciseux [Ref. 9] show that a tradi+ional 
approach to the software problem has led to the practices of 
Simply tacking on maintenance aids as an afterthought. The 
concept of software maintenance, paz- -cuüulazly ir -scne ching 
cther than that of a corrective nature, seems to be some- 
thing that receives very little attention. 

Now let's lock at the software maintenance problen 
as viewsd by managers who plan the maintenance effor+ based 
on how they perceive the maintenans2 problen. Lentz and 
Swanson (Ref. 5] report in a study that managers perceive 
the lack of user kncwleige as by far the most dominant 
problem in the maintenance effort. Following the user 
knowledge problem in crder of highest to lowest significance 
were: progranmer effectiveness; product quality; programmer 
availabiltiy; machine requirements; and finally system reli- 
5 ty. When the system is properly documentec, user 
knowledge about the program development and” maintenance 
technigues can be increased. Increased knowledge can cause 
more efficient use of the maintainer's time thus making the 
Maintainer available more often to perform other tasks. 
Documentation can also be used to racord machine require- 
ments in such a way that they are made available for consid- 
eration in maintenance decisions. hen documentation is 
used prcperly, it can reduce these problem areas as 
mentioned and result in an overall increase in system 
reliability. 

The study further revealed a misconception commonly 
held by managers. Problems were perceived by managers to be 
greater if a lot of corrective maintenance time was spent on 
the system. As menticned earlier, corrective maintenance is 
not the big time consumer whereas perfective maintenance 


does in fact consume the bulk of tha maintainer's time. 17 
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is inter moe =O DOLE that there yera no Significant find- 
ings to indicate that there was any time at all allotted to 
ths maintenance personnel for the act of performing purely 
perfective maintenance. When it is understood that most of 
the actual maintenance time is spent in making program 
enhancements (that is, the perfective mainterance), EE 
becomes clear that managers need to re-evaluate the way they 
allot time for maintenance. 

Another reascn for maintenance problems can ba 
considered to be both a cause and a result of the above 
Mentioned problems. This reasen for maintenance problems is 
mre lack of Jood documentation. Schneidewind points out 
that cne of the problems involved with softwars maintenance 
Sanet” no tracebility 1s built into the software. IS 
problem could be resclved with the appropriate documentation 
technique. In order to convey ideas from old maintainers to 
new maintainers, good documentaion is needed. For example, 
formal specifications of the problen for which the system is 
designed must be presented and documented sc that 5 later 
change *c the program can be evaluated against the docu- 
mented reason for a particular design systen. This thesis 
will explore the documentation problem in more detail in 
later chapters. 


6. olutions 


As implied from the above discussion of the causes 
of the software maintenance problem, the use of proper docu- 
mentation is the key tc many maintanance probiem solutions. 

The solutions reguire the cooperation of managers, 
users, and maintainers. Good maintenance techniques are 
also necessary and must begin at tne design and require- 
ments phases of the life cycle. Several ideas are presented 
by Schneidewind to ensure good maintenance practices and 


good documentation. 
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መ” ሑቱ. good maintenance techniques must be 
Pearnned fron the beginning of a software project. This 
geans that the project must be dasigned with maintenance 
integral to the entire life cycle, not added later when the 
project is completed. Since enhancements take up most of 
the maintenance effort, it is necessary that the design 
ideas incorporate the understanding that enhancements will 
tak2 place and that managers plan Maintenance time 
geceordingly. 

One way to enhance maintinance personnel under- 
standing is to use modularity techniques in the design of 
the software project. This means that common ideas or 
concepts shoula be kept together in a logical sense «hat 
would be easy for the maintainer to follow utilizing proper 
documentation. The documentation should be able to convey 
the module concepts used in the d2sign of the software to 
the person wh needs to make software modifications. 

Along with the modularity tachniques, the idea of 
ind2pendence among code, data, ani data base is in order. 
This independence allows certain amounts oz code, functions, 
Subroutines, etc. tc be changed without devastating effects 
taking place in other portions of the program. Information 
hiding techniques are valuable when designing a progran 
with modular independence for ease of maintenance. 

Schneidewind also gives several ideas concerning the 
proper development of documentation along with the project 
in order +o ensure the ease of maintenance. On2 idea is to 
design the documentation first. Many a programmer knows how 
tothersome this task can be. Just think of how many times 
the flow charts or refinement procedures were written after 
the program itself was actually written. The problem with 
writing the documentation after the program is completed is 
that the documentaticn that is supposed to aid in the devel- 
opment and decision making processes cannot possibly be 
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used. SS CRS ስመ ۲ے‎ መጋ" becomes Static 


2n ውጋ. 
That is, all the dynamic creativity cannot be included in 
the process of documentation and all we see is +he final 


resulting document. This is very much like a co 
professor receiving a math or physics exam with only the 
answers and no actual work shown. 

Another idea for good documentation is that <he 
specificatiors and standards should require aids that 
promote the understandability oF the progran. This 
includes the concept of providing comments in the progran 
listing, references in the source listings for certain soft- 
ware specifications, and any other references necessary to 
trace through other related documents. 

Systen specifications should be designated as to the 
kind of infcrmation that is to be conveyed to the maintainer 
via documentation. This idea implies tnat certain types of 
Heeumentaticn convey certain kinds of informa*ion, and that 
only certain bits of information are required for certain 
maintenance functions. The idea of different kinds cf docu- 
mentation delivering various ን ۶00256270653108 and the 
effectiveness of the forms of documentation will be 


discussed below. 
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III. SOFTWARE DOCUMENTATION 

This chapter covers many aspects of software documente- 
tion. Some background is given on documentation ¿in general, 
including a discussion about the purpose of documentation. 
The various categories of documentation are explained based 
on the characteristics of the documentation and the needs of 
th2 user. Control and developmant documentation is 
discussed, as is static and dynamic documentation. Also the 
ES ries Of zmppiicit and explicit documentation as they 
pertain ee the maintenance role are explained. 
Documentation dependencies with regard to skill levels and 
position level of personnel on the documentation team are 


G2 seussed. 


A. DOCUMENTATION BACKGROUND 


The pzimary purpcse of docunertation is to impart knowl- 
edge about the system to pertinent personnel by trans- 
می‎ >>. treccrded information. Other Gener “he code itself, 
E ORLY source of writtea information about the program is 
tne documentation. Misunderstandings can occur when our 
informal, abstract ideas are translated into formal, 
concrete pieces of information. This information transfer 
is accomplished by recording oa various forms óf infor- 
mation storing media. This includas such methods as manu- 
ally recording facts on paper, or electronically placing 
them in a computer memory. These various information 
recordings become forms of documentation. The documentation 
challenge, then, is to find a way to ensure the unmolested 
receipt of intended concepts by the documentation users. 


When this challenge is met effectively, documentation is 
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considered ቲጋ have accomplished its goal of successfully 
conveying relevant. information from one person +o another. 
Chapter ¥ discusses in more detail the particular dcecumenta- 
tion formats and their relative effectiveness. 

One cannot hope to effectively transfer knowledge about 
the system by simply flooding the maintainer with all tha 
information that can possibly be assembled. It is necessary 
to distinguish between types of documentation, and discern 
the type of informaticn that each conveys. Not all types of 
documentation are adequate for all types of information 
transfer, and consequently, not good for all types of nain- 
tenance chores. 


B. DOCUMENTATION CATEGORIES 


(te the asa Of transferring information is clear, the 
idea of what kind and how much information to transfer is 
not so clear. The amount of information to transfer is both 
task dependent and pregrammer dependent. Both the mainte- 
nance task to be accomplished and the level of expertise of 
the maintenance person should be considered when deciding 
upon the category of documentation to be used. For example, 
if the documentation is to be usei by someone who is very 
familiar with the system and the type of changes to be 
applied to the program, the documentation needed would be 
of a level that is far less detailed than that of someone 
who had never worked on the systen before. It would be 
helpful to find ways to categorize documentation in order to 
gain an understanding of the values of each. 


1. Internal and External Documentation 


One way of categorizing documentation 1s based on 
how the documentation itself is transported (internally or 


externally). Internal documentation is the documentation 
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that is carried along with the coda (perhaps in a seperate 
l3. It is usually embedded in the form of comments cr 


cross reference listings, and is not executable. ine 


ሀ] 


is an 
ግ + pas. Of the program, so it is always available. I+ 
is easy to maintain because it is as 2asy to update as “the 
code itself. When a software modificazion is made, it isa 
Simple matter +o modify the internal documentation. Because 
of the ease of update, internal documentation is considered 
by programmers to be very reliable, and the programmers 
have a high level of confidence in the currency and accuracy 
of the internal documentation. 

External documentation is the documentation that 
exists outside the source code of the program. Thess 
includes such things as data flow diagrams, flow charts, and 
any other mode of recording program information that is 
not an integral part of the progran. This type of dGccumen- 
pacuon 2s mcre d3fficult to maintala than the internal docu- 
mentaticn because it usually exists in hard copy only, thus 
pen and ink Charges are required for making documentation 
modifications. Because of the difficulty encountered in the 
updating of external documantation, often it is not updated 
when the system is modified. This leads to a low level of 
trust amcng programmers with regard to the reliablility of 
external documentation. This low level of confidence in the 
currency of external documentation is often perpetuated by 
the feeling that there is no reason to update it since it is 
not current anyway, and even if it is updated, it won't be 
trusted. 


2. Dynamic and Static Documentation 





Documentation can also be considered to be either 
static or dynamic in nature. Dynamic documentation involves 
the conveyence of ideas about the actual developmental 
thought processes. This would include the recording of 


idas that begin With the first thoughts in the conceptual 
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phase ot the life cycle. It &elso includes the mistakes ۹ 


(ሀ 


and the ideas considered and rejected for any reason. Prio 
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Mistakes and the reasons as to why they were mistakes can 
provide vital insights to the maintainers when new changes 
are being considered. 

The dynamic natura of the documentation comes fron 
the fact that the entire decision-making process can pe 
actively recorded and transmitted to the receiver of the 
documentation. The significance of this type of documenta- 
ten, then, is the fact that later enhancements to the 
program (remenber, itis the enhancements that make up the 
biggest part of the maintenance workload) can bs considered 
malen: Of Original design decisions. Much redundancy in 
the consideration of enhancements stands to be saved when 
proper dynamic documentation is usi. 

Static documentation can be considered ሂር be the 
Mizal product” of the documentation process. It is a 
recording of the current static state of the program at some 
Mount in tame, and it does not provid? any indication of the 
dynamics involved in the avolution of the program reaching 
that state. This type of documsntation includes things 
such as a system or program flow chart or a rescurce 
diagram. It is this type of documentation that conveys the 
ideas of the program or system itself, and how it functions. 

It must be realized that both of these types of 
documentation are necessary for the roper transfer of 
knowledge from the designer to the maintenance person. 
Without both types, either the original thought "flavor" of 
the designer's intent is lost with the passage of time, or 
the understanding of the processing of ቲከ5 program is 
lO0St. 
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DI ን ።፡ ካፐ and Bxplicit Documaatation 


Anothar categorization of 002137 732292 وت‎ 45 
pron of 1gplicit and explicit documentation. ee 
documentation can be thought of as the documentation that is 
physically available, in whatever form (dynamic cr static), 
at varying lavels of detail. PA pele. docunentaticn eccuta, 
therefore, include documentation such as comments, manuals, 
and flew diagrams. 

Implicit documentation is a more subtle and abstract 
type of documentation. This type of documentation consists 
of the "essence" of a program that is made available by 
1 تت‎ 3110219 information from One or more forms of either 
the dynamic or static documentation. This concept of 
implicit documentation, then, involves a synergistic effect 
that provides a high level understanding of the system 
INOUE large amounts of explicit physical information 
necessarily being accessed. Implicit documentation provides 
ቄ ። ስ ፡ ጥገ Picture for the receiver of the information when 
various amounts of physical documentation are assimilated. 
Thus implicit documentation captures the concept of trans- 
ferring betwean individuals knowledge that would be diffi- 
Gree tO inpar: through language or 2xplicit documentation. 

It is sometimes very difficult to convey abstract 
ideas through the use of explicit informational documenta- 
tion, yet enough documentation (but not so much as to over- 
wheim) must be explicitly available to successfully generate 
the implicit documentation notion. This supports the 
concept cf minimal documentation. 


6. DOCUMENTATION DEPENDENCIES 


Yet another way to categorize documentation is to 


consider audience-dependent and life cycle phase-dependent 
documentation divisions. It is necessary to understand the 
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needs cí the audience for which the documentation is 
intended and also the life-cycle phas2 to which the documen- 
tation is related. These determinations are necessary so 
that the documentation user who is knowisdgeable about the 
system is not completely bogged down by the effort of 
trying <=ር sort through a myriad of details that have nothing 
to do with that particular maintenance task, or are super- 
fluous in the sense that the user already knows the neces- 
sary details. By the same token, it is inefficient tora 
person who is not well versed in certain aspects of the 
Beogect to spead many hours searching through lots cf docu- 
mentation just to find out something specific about the 
program on which maintenance is to be conducted. There 
must indeed be a balance between ver detailed and high 
level documentation. Tha idea is that unnecessary work that 
adds to the overhead of the maintenance task should not be 
given to the maintenance person. (More is discussed in 
Chapter Y about how to access the proper level of detail of 
documentation. ) 

When considering audience-dependent dccumentation, 
several factors must be taken into account. These 
factcrs include the reader's skill level (or familiarity 
with the project), the reader's position relative to the 
maintenance job, and the particular type of maintenance to 
be accomplished. A skilled person can be defined as one who 
understands basic organizaticn programming policies or tech- 
niques. The skilled person often possesses the quality of 
familiarity discussed earlier. 

Different kinds of documentation are appropriate for the 
different factors mentioned above, and in ordér to run the 
maintenance job effectively, these kinds of documentation 


are critical. 
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1. Skill Level 


In considering the idea of skill level for the docu- 
‘mentation user, the level cf documantation detail shou 


of concern. The documentation should be of sufficient leve 
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so as to give the user the precis2z amount of detail neces- 
Bay to carry out the required maintenance function. This 
means that, if the user is skillel, the provided document 
should not contain minutely detailed explanations of the 
program if the ideas are commonly understood. On the other 
hand, “he documentation must be an adequate level o 
SO as to provide the unskilled person with the needed 
of svstem specifics. 

Ic 1553 Of “explicit and amplicit documentation 
come into play here. For the highly skilled user, the 
amount of physically explicit documentation can be small and 
condensed in nature. Tis Seamount Of implicit information 
would be large because the skilled user can accept high 
level concepts that dc not have to bs explicitly described. 
That is, a highly skilled user can make use of implied 
ONS, such as the notion that the data in a certain 
program goes through a "sort and eliminate" routine. Here 
the explicit documentation would consist of the information 
that the data is sent to the routine, while the implicit 
information would be made up of commonly understood details 
of the routine itself. 

AS foc the unskilled user of tne documentation, the 
nature of the explicit and the implicit idea conveyence 
would be quite different. The unskilled user would need 
much more explicit information to absorb the sane amount of 
knowledge of the portion of the program to be maintained. 
The necessary explicit information would likely include many 
of the specific details of the "sort" and "eliminate" 


routines separately. Decrease tor elimination of 
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certain data were understood by the unskilled user at this 
level of detail, then those details would be considered to 
Ne በለ]! cit intormaticn. If those criteria were unknown to 
“s unskilled user, then the explicit documentation concept 
must move dcwn another level of detail to incorpcze*te these 
details explicitly. The levels of detail are translated 
continually from the implicit to the explicit realm as the 
need for information detail (determined by the skill level) 
moves down <o lower levels. 

Conversely, as the skill level "of the user 
increases, information and details required by the user nove 
from the explicit to he implicit realm, thus allowing 
broader concepts to be absorbed by the user. AS more 
implicit information is required by the user, a corre- 
sponding lesser amount of explicit information (or documen- 
talon) is required. 

The consequences of having less explicit information 
being required mean that less documentation (and conse- 
quently iess overhead) needs to be sorted through in order 
to complete the maintenance task. The end result is that as 
Skill level increases, less tim? is required for the 
specific maintenance task, and a corresponding maintenance 
efficiency results. 


2. osition 


A look at the idea of a person's position with 
regard to the maintenance effort is useful. 2 6 - ELO 
bet*er understand how the relative position of the person 
utilizing the documentation affects documentation needs, 
first we must know whether the person is considered +o be a 
maintainer, a manager, or a user. 
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a. Maintainer 


The maintainer is defined to be the persen who 


‚I 


ከ ሩቲ ር يږ‎ involved in the actual act of maintaining the 
program. The maintainer requires the lowest level 
abstraction of documentation, or the nost detailed level o 
information because of the actual physical maintenance tha: 
is accomplished. The type of documentation required by the 
Maintainer t5 successfully complete the maintenance task 
then will be on a level that is fairly detailed. The depth 
of detail required will of course be dependent upon the 
Maintainer's skill devel or fagiliarity as discussed 
earlier. The documentation type will be of the kind that 
will promote the detail necessary +5 compiet= the job. The 
amount of explicit documentation will also be determined by 
skill level and familiarity. 

As far as dynamic documentation is concerned, 
th maintainer relies less heavily on this level of documen- 
Eee on han on the static documentation. The maintainer is 
very concerned about the present state of the progran 
because the present state is what is to be modified. The 
decision as zo whether or not to make the modification is 
usually nade a+ a higher level, and thus the dynamic docu- 
mentation will be better used at that higher level (probably 
the manager level). 


b. Manager 


The manager category can be defined so as to 
include anyone who is directly connected with the mainte- 
nance of the systen, DUO atively involved with the 
actual physical maintenance of the project. This پ٥٦‎ 
include the maintenance team leader in the supervisory role, 
the department head, or higher level decision makers. The 
type of documentation that the manager needs should be of a 


36 








much higher level of abstraction zaequiring lass detail -han 
that required by the maintainer. This means that much more 
documentation of an implicit natures is acceptable in orde 
to meet the needs of the manager level personnel. The 
greater the amount cf implicit documentation n¢eeded,  *he 
less the amount of explicit documentation necessary. 
Likewise, the less the detail level of the explicit documen- 
tation, the less the amount of dstails through which ths 
manager must sort. The smaller andunt of detail required 
leads to the saving of time and money. 

The manager could very well be the biggest user 
of dynamic documentation. The manager at the main-terarcs 
group supervisor level is likely to be the one who must look 
at the way prior decisions were made in order tc verify جلاک‎ 
practicality of requested maintenance enhancements. The 
manager might want to avoid re-deciding something that is 
already a given and has been recorded in the dynamic 
dccumentaticn. 

The manager could also be a very heavy user of 
static documentation in the sense that it might be necessary 
to reference the present status of the maintenance effort in 
crder to properly set up the maintenance tean. Thus the 
manager must rely heavily on the static documentation to 
understand the program status after design and also to 
modify the existing documentation as the program is modi- 
fisd. This also implies that dynamic documentation by the 
maintenance team is cccurring alonj with program modifica- 
tions, and the manager is responsible for updating or 
creating the appropriate dynamic documentation. 


62 User 


The user is anyone who actually uses the system 
(the pilot using an avionics system, a fire control techni- 


Cian on board ship, etc.) The user night be someone who is 
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considering purchasing services or products from the company 


aguas interested in the stability of the company as 


yy 


whole. The system is a vital part of the company, and 
consequently “he user might be interested in the program or 
system frcma very abstract point of view. Other than 
specific user's manuals and system operational guides, the 
user needs little or no detailed information and can 
=> ም ተሪ a large ancunt of implicit documentation. The 
anount of explicit documentation required for the user will 
be very small indeed, perhaps even a simple listing of the 
systems cz programs available to the company. The user 
Simply wants to know what capabilitias are present and if 
they meet the user's needs. Any eerucches detail is 
Superfluous. 

The user is probably not in 
dynamic documentation and has vn little interest in 
static documentation. He does not really re about the 
design decisions that occurred during che development of the 
systen, but merely about the fact that there exists a 


system sufficient for his needs. 


D. ROLE OF DOCUMENTATION 


The idea of implicit and explicit information can be 
utilized here. Returning for a moment to the example in the 
last chapter concernin the likening of the receipt of cne 
final piece cf documentation to that of a college professor 
receiving only the answers on a physics or math test without 
explanation as to how the answers came abou“, more 
discussion is in order. The dynamic nature of showing the 
work, whether the work was on an exam or on a program, helps 
both the programmer and the maintenance person (cr the 

tudent and the professor) follow the design and development 


of ideas. Since documentation, as described earlier, 
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involvas the transfer of ideas, Dues 1:31 “cha= theses 
509685 ከ5 transferred dynamically in the form of progressi 
@ocumentation. It is difficult to undsrstand he cthough* a 
development process that goes into a problem when all chat 
is seen by the receiver of the information is the final 
Sout 20n. 

We need not worry that the final documentation product 
might contain some recording cf our initial erroneous 
efforts. i Eat E might pe helpful to the maintainer if 
me initial trial and error efforts were made available. 
It could save the maintenance person che redundant effort of 
trying tc rethink the designer's iisas in order to possibly 
change a previous logical decision. 

The complete documentation could also keep the  main- 
tainer from overlooking some critical piece of infcrmation 
that would make the newly proposed enhancement an obvicusly 
bai move. Another advantage of documenting the creative 
process is that ideas that were not feasible (technologic- 
ally or environmentally) at the time of design, and ccnse- 
quently rejected, could be used during the maintenance phase 
as a result of system reguirement changes or technological 
advances. 

Ideally, then, the maintainer will not receive as docu- 
mentation thing as simple as the statement that 2 
system will use red ribbons for printed output. This gives 
m® mmdacaticn as to how much thought, if any, went into the 
decision. When the suggestion for an enhancement to allow a 
different color for printed output, the maintenance person 
must try to second guess the designer's decision as to why 
red was selected, and if another color is possible. If this 
knowledge wera made readily available, the maintainer could 
possibly head off an expensive analysis of colored printed 
outputs that would discover that the designer already knew 
that red printouts were the only ones that could be read 
under the special lighting needed f5r a security project. 
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IV. DOCUMENTATION HIERARCHY 

The idea of a documentation hierarchy is introduced 
along with an =xplanation of the proper use of the hierarch- 
ical organization and how it promotes the concept cf 
Minimal documentation. System and program documentation ۶ 
discussed in detail as they relate to both the system hier- 
archy and the maint2nance task. 


A. SYSTEM DOCUMENTATION HIERARCHY 


One preblem that faces the manager is how to wade 
through all available documentation in order to glean out 
the pertinent information for the present task without 
getting togged down with a massive volume of material. Th= 
sane problem is faced by the maintainer who may not need to 
know ail the system design information when the task at hand 
(as determined already by the managerial decision-making 
process) is simply to modify a small section of code. It is 
clearly wasteful in this case to force the maintainer to 
sort through huge amcunts of irrelevant material concerning 
high level system information just to locate information 
pertaining to the immediate code molification task. 

The user requires information about the system on a high 
conceptual level, but zhe deluge of unorganized documenta- 
tion with all levels of detail would require time ccnsuming 
searching, and most of the detailed information would be 
utterly useless. i 

A solution to the problem of unorganized levels of 
detail in documentation is to construct an organized hier- 
archical structure for the various forms of documentation 
based on the level of detail. This documentation hierarchy 
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Gan Ppeow de"precisely the appropriate level of detail in the 
available  documentaticn for the receiver, regardlass o 
gpether the receiver is the user, manager, o> maintainsr. 


Figure 4.1 provides an example of a system documen-ta-i 


O O 
Fh 


hierarchy organization that indicatss the various levels 


detail involved in the documentation of a system. 


۹ 


All of the documentation is available to the prove 
r the 
least amcunt of detail necessary (thus promoting the concept 


receiver in a concise format that gives the receive 


of minimal documentation as  mentionsd earlier). As mor? 
detail is needed, more explicit documentation is accessible. 
This promotes understandability and contributes to an effi- 
clent maintenance effort. 

The system documentation hierarchy of Figur: 4.1 shows 
arrows that indicate a downward and upward flow of documen- 
tat-or access. As progress is made down to lower levels on 
Bawze 4.1, more detail is attained in the documentation. 
Conversely, as movement is made up th¢e levels, less detailed 


descriptions anû larger concepts ara accessed. 


B. SYSTEM DOCUMENTATION 


To understand more about the system documentation hier- 
archy, it must be understood what is meant by system docu- 
mentation. A system can be defined as one or nore programs 
Mao Ran conjunction to perform a particular function. 
The system can be very simplistic, such as a Simple vote 
counting systan, or it can be very complicated as in the 
case of a sophisticated weapons systen. Since a systen has 
been defined as the combination of 2n2 or more programs that 
perform a function, system documentation is defined as the 
documentation of the overall system life cycle from the 
project conception phase through the support phase. 
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Figure 4.1 system Documentation Hierarchy. 
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System documentation contains recorded 370 2 N OE 
ን የፕ admi ng to the complete description of the evolutior oda 


We ۰۱۸و‎ 201095890 its life cycle. Te includes د‎ FEC of 


the development  prccess and the maintenance history in 


mENUCr implicit or explicit fora. System documentation 
contains both dynamic and static information and can be 
used by maintainer, manager, and user personnel. The 
specific form of documentation is dependen upon the 


requirements of the task to be accomplished and the needs o£ 
the receiver. 

Since a system is made up of one or more programs, 
Program documentation is considered to be included as a part 
of the system documentation. In Figure 4.1 program docunern- 
tation consists of levels 3 and 4. Both system and program 
documentaticn are discussed in greater detail later in this 


ehapter, 


1. Level 1 


The overali system documentation follows a hierarch- 
ical structure with varying lavels of detail as shown in 
Eure 4.1. The highest level of abstraction for ths 
system, level i, includes a narrative description of the 
system itself and a description of the system environment 
along with any assumptions about thes system. The environ- 
mental description would include information pertaining to 
the system hardware and softwar? environments. This 
includes system restrictions and linitations that might 
result from certain hardware or software constraints under 
which the system must operate. “ilitary applications such 
es an avionics system or a submarine weapons system would 
dictate specific environmental restrictions because cf the 
very nature of the system activities. 

ies Din. this level chat the documentation 


contains the most abstract information about the project. 
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This level of detail would probably be most often used b: 
mere User "personnel, but this non-~istailed narrativ 
could also be of use to the manager and main? 
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personnel who require an overall understanding of the 
system. 


2. Level 2 


Level 2 is the next level of abstraction "ox 
Merärchical structure amdeconccuns slightly nors” detail 
than level 1. This level includes any system flow informa- 
tion, such as perhaps system flow diagrams, and systen input 
and output descripticns. The inter-program module descrip- 
tions are included in this level; this level gives informa- 


tion about how individual programs re inter-related in the 


ሠ 


syszen. This type of information 


a 
ወ 


an be conveyed with th 
use of narrative remarks. 

Since level 2 system documentation includes informa- 
tion such as system input and output specifications and 
requirements, maintainers and managers find this input/ 
output information to be valuable because they must ensure 
that the maintenance of the program is accomplished in such 
a way “hat the output requirements are correctly attained 
when the appropriate system inputs are given. 

Managers need to know the system input ard output 
specifications that fit user needs in order to ensure main- 
tainers have the proper information as translated from the 
user (who very likely is not as technically oriented as the 
manager or tha maintainer) requirements. Thus the managers 
can take the user input and output requirements as requested 
by the users and translate them into an understanding 
between the maintainers and the users in order that effec- 
tive maintenance can be accomplishel. 

Users obviously play an impartan* role in the gener- 


ation of the general input and output specificaticns, and 
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these specifications must make sens: to the managers befor 


the maintainers can ke expected to understand ard perf 


O 


خو 
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fu 3 


maintenance tasks. An understanding between users ar 


ጋ 


managers must therefore be reached as to what the users want 
(or think they want). The prudent user will heed management 
advice when considering reasonable input and output formats. 

System logic information is also a part of level 2 
of the system documentation hierarchy, and it conveys thea 
Ma Mal flow of the project. This logical informatidcn could 
include a narrative section that describes the purpose of 
the system and how it is logically constructed. Tha hiers 
archy of programs, functions, and modules can be described 
3۰۰۰۰۱5۳8772+ ۰ The system flow documentation concerning 
the relationship of the individual modules can take the 
form of system flow charts or flow diagrams with accompa- 
nying comments. 

The inter-program module descriptions provide infer- 
mation about the relationship o? the programs to the system 
ara to eaca other. 1! መ= ዮ። ve characteristics or 
program environmental considerations are included in the 
inter-module narrative. 

The rest of the lower levels of abstraction make up 
the program documentation pertion of the documentation hier- 

EIR It is in these levels that the dearee of detail is 
such that the system is no longer the focal point of the 
documentation, and the program specifics are brought into 


view. 


C. PROGRAM DOCUMENT ATION 


Program documentation, as indicated above, consists of 
the recorded informetion about the program itself. It is of 
a more detailed nature than the system documentation and is 


most useful for the manager and maintainer. t contains 
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antormarcion pertaining to program module construction and 


loque Flox. 03:3 2-1-1 ته‎ data low, and control flow 
Ene Ecs dre recorded so that tha documentation receiver 
has relevant program information available. Programming 


methodology techniques and maintenance history become par: 
of the program documentation as well. Dynamic documentation 
describing inter-module concepts and structures is included, 
but static documentation makes up the bulk of the progran 
documentation. Specific Swpliciz forms of program documen- 
EON Includes flow charts, English narrativa statements, 
resource diagrams, and Petri nets. 


t system 


ct 


While all of the levels in Figure 4.1 represen 
documentaticn, levels 3 and 4 can ba combined =o make up che 
program documentation portion of the system documentation 


hwocarchy. 


1. Level 3 


Level 3 of Figure 4.1 is the first level of the 
program documentaticn and conveys a particular program 
0۲ .۰م‎ Parti colar progran constraints “hat deal with 
specific programs are described in Level 3 along with any 
high level narrative about the program itself. Level 3 does 
not contain any inter-program relationships with other 
programs. It is the level that deals with strictly a single 
program. 

This level of abstraction is more detailed than 
levels 1 and 2, and is very useful to both the manager and 
the maintainer. The manager neeäs to keep the high level 
program concept so that the maintainers can be properly 
Managed without forcing th2 maintainers to be concerned with 
any unneccessary abstract information. The manager must 
keep the pregram concept in mind and relate it to the rest 
of the system (level 2 and higher). 


46 





Mel lana ner Cam» however, use this leval oO 
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የከ 


detail to aid in the understanding of how a particular main- 
tenance task is constrained. The manager is responsible for 
the overseeing of the jater-program module relea-icnshirs, 
but a knowledgeable maintenance person can be of 
immeasurable aid to the wise manager in this area. 


2. Level Y 


The next lower level of abstraction, level 4, 
provides the greatest level of detail. This level is used 
very heavily by maintenance personnel, and often by nanage- 
rial personnel. This level consists of very  de-siileá 
descriptions such as program flow information and input/ 


ouput rorSats. Much of this documentation is vary explicit 


in nature. Teacecanıbs: Star. ት 0 2072. Flowcharts, 
inter-code comments, logic, and data flow diagrams are 
included in this level of documentation. It is this level 


of detail that describes program modules in enough detail so 
as to promote understandđabi lity among maintainers. 

While maintainers are the heaviest users of progzam 
documentation, and users are the primary users of the higher 
level system documentation, managers must bridge che gap 
between the two levels of documentation. Managers are 
involved with high level decisions that require an overall 
system understanding, yet they must also be involved with 
some of the lower levels of program documentation in order 


to properly manage the maintenance functions. 


D. DOCUMENTATION HIERARCHY UTILIZATION 


The documentation hierarchy is set up so that anyone can 
access the hierarchy at any of the indicated levels, and 
thus ke exposed to the level of detail characteristic of 
that particular level. If more detail is needed for a given 
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task, then a simple move down to the next levei for grea-er 
Hc cols permitted. BJ CES Sane 2۴ 51 Let itis determini 
that the level accessed is too detailed for the varticular 
needs of the person using the documentation, then the arrow 
is simply followed up toa higher level of abstraction that 


neets the desired needs. 

Each form of documentation, then, is catalogued as to 
sts detail level, anda menu format (either paper or elec- 
trenic) can bs utilized to directly access the level needed. 

Mech the capability of moving either direction in the 
Blsrarchy structure, Beat lexyamy)jey «lS Built into the 
System, and only the exact amount of documentation needed is 
accessed. This promctes the minimal documentation concept 
and, therefore, keeps the documentation overhead down to a 

inimun. The amount of useless information that must be 

۱11 تت‎ through in ozder to find the proper documentation is 
kept low as a result cf proper utilization of the documenta- 
"ን hierarchy concept. 
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V. EVALUATION OF FORMS OF DOCUMENTATION 
Chapter III discusses the various types of documentation 
and how they relate to the maintenance effort. Ir is impor- 
tant to carry the documentation discussion further and talk 
about not only the types of documentation that are useful, 


but also some specifics as far as physical arrangemerts ar 


(5 


eon ered. The discussion will focus on explicit types of 
program documentation, and how som2 of the physical charac- 
1 IGS Cf the documentation affect the efficiency of 
Maintenance performance. 


A. | EVALUATION EXPERIMENTS 


When dealing specifically with programming documentation 
(levels 3 and 4 of Figure 4.1) which is most oíten used by 
Maintainers, it would be helpful to understand which 
different foras of documentation are most effesctiva. 
Chapter III discusses the different types of information 
utilized by users, managers, and maintainers, depending on 
the maintenance task and the documantation receiver. This 
chapter discusses some specific forms of documentation and 
how effective they can be in promoting understandability for 
efficient program maintenance. 

It has been determined by General Electric studies 
(Ref. 10} that th2 best form of documentation to be used for 
maintenance is heavily dependent on the type of progran 
processing that takes place, in particular whether it is 
sequential or concurrent processing. 
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1. Documentation for Sequential Processing 


In determining the most effective type of documenta- 
tion format for sequential processing, a primary concern 
mus“ involve the type of symbology used to present the 
information. It would be beneficial to ascertain the best 
form of symbology as seen by the naintenance personnel in 
terms of maintenance efficiency. 

The three symbology types used in tke General 
ር... ሰ Studies consist of narrative  Englist text, an 
abbreviated orogram-like language called Program Design 
Language (PDL), and ide»graus. The narrative text is 
frequently embedded in tha source coda as either glcbal or 
in-line comments. Hee PDL S Ssaccinct and uses strictly 
defined keywords to describe arguments or predicaté¢s. 
Ideograns are often found in flow charts and HIPO charts. 
Sets of ideograms represent processes in a program 
[Ref. 11]. 

Ancther primary concern which must be dealt with 
when weighing effective documentation is the issue of 
spatial arrangement. Spatial arrangements can aid main- 
tainers in understanding the flow of control in a sequential 
program, and it would be helpful if the best spatial fcrmat 
could be determined. The spatial arrangements provide 
different ways of representing control flow and nesting 
levels. The spatial arrangements used in the experiments 
are sequential, branching, and hierarchical representations. 

The sequential arrangement represents both the 
control flow and the levels of nesting in a vertical manner. 
The branching arrangement presents the flow of control in a 
vertical manner while the nesting levels are presented hori- 
zontall ¥. Finally, in the hierarchical arrangement, the 
control flow is represented horizontally and the nesting 


levels are presented vertically. 
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The sequential processing experiments were designed 
to run the gamut of many of the maintenance tasks performed 
by programmers. The tasks included answering questions 
about pzcgram coding, program debugging, program modifica- 
En, and program operation. The maintenance tasks were to 
be completed using the various foras of documentation being 
tested. The studies were conducted with professional 
programmers who were asked to answer questions about 
programs. The programmers were allowed to reference only 
the varicus forms of documentation having the spatial and 
synbology characteristics mentioned above to get information 
about thse programs. 

Nire SpEcituication fosmats were presented tc ths 
programmers for their use in the experiments. Bach of the 
three types of symbolcgy was presented in sach of the three 
spatial arrangements. 

The participants were also asked to choose which 
format of documentaticn they found to be the easiest to use. 
This choice was then weighed against the type of documenta- 
tion that preduced the best results in terms of maintenance 
effectiveness. 

In the first experiment, the programmers were asked 
to answer backward and forward-tracing questions and input/ 
output questions about the program using the test documenta- 
tion provided. 

The results showed that the sequential PDL, the 
branching PDL, and the branching ileogram versions of docu- 
mentation were the most effective for answering the tracing 
questions. 

For the input/foutput questions, 59-3961 1 7 7 
differences were found between the forms of documentation. 
The most preferred combinations of documentation formats 
were the PDL symbology and the branching spatial arrange- 
ments [Ref. 11]. 
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In another experiment programmers were asked to 


completes the coding of portions of programs referencing onl: 


mas 


(D 


the documentation under test. In this experiments ch 
English narrative format took sega 7 6 ۳۳ ۹ ۶۴ 
produce code than did the PDL format. Tte English version 
also produced the largest number of errors, while tke PDL 


O 


produced the smallest. 

The spatial arrangement effects were not signifi- 
cant, but the formats of the sequential PDL and the 
branching PDL arrangements produced the best experimental 
results. The sequential English version produced the 
poorest periormance. 

The programmers also chose the PDL 2 00 
arrangements 2S the preferred format combination. 

In yet another experiment the programmers had to 
correct  error-seeded programs, again utilizing only the 
documentation under test as a source of prcegram information. 

The best results in performance occurred with tha 
PDL and idéogram symbologies for this experimento. The 
Spatial effects were again not significant. The sequential 
and branching PDL formats proved to ba high performers, as 
did the branching and hierarchical idsograns. 

The programmers nad no preference for the  *ype o£ 
synbology in this experiment, but they did prefer the 
branching spatial arrangement {Ref. 13]. 

Though slightly different results were produced in 
this experiment depending on the maintenance task, overall 
the indication is that performance is improved when the 
symbology is of a succinct nature, such as in the PDL 
format. The English narrative proved to be too wordy ang 
awkward to provide efficiency when attempting software 
maintenance. 

às for the spatial arrangement issues, the best 
overall performance resulted from the use of 3 ranching 


arrangement in providing the clearest display of control 
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flow. Due EDL bramehirg format, then, seemed to promote 


understandability for the maintainer, and the PDL branching 


- 


format was selected by the programmers as the easiest 
overall format to use. 


2. Docume: 


tation £or Coen 





Since much of today's program processing is concur- 


ብ. 
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t, it is wise to investigate documentation effectiveness 


t-h 
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O tne concurrent realm of processing. Corcurz en: 
processing of programs entails two or more portions of the 
program executing simultaneously. Because of the complexity 
involved with concurrent processes, programs that contain 
Esneurrent processiag must be carefully documented. Tore 
portant to convey information about the control flow of 
the program and «he sharing of resources. 

The formats of documentation used for the Genaral 
لک له وت ل2‎ Studies Of concurrent processing documentation 
(Ref. 14] consist of three types: PDL; resource diagrams; 
and Petri nets. The first form of iocumentation is the same 
بحے‎ The PDL 


PDL as used in the sequential processing tes 
emphasizes -he control-flow characzesristics of the program. 


The second form of documentation, the resource 
diagran, vlaces emphasis on tha concept of providing 
resource sharing information to the progranner. The 


resource diagram uses communication circles containing 
abbreviated English statements to convey information about 
the relationships between processes. Natural English state- 
ments provide narrative information contained in process 
boxes to describe the process itself. Resource diagrams are 
arranged spatially in a branching format similar to the 
branching organization used in the sequential experiments. 
Mee talzd forme cf documentation is that of a Petri 
net. Petri nets have nodes that contain information that 


inaicates resource usage for required tasks, while 
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Em Tol flow information is conveyed with a constrained 
lenguage description. The Petri net format of documentation 
places equai emphasis on control-flow and resource sharing 
information. The spatial arrangement of the Petri net is 
also similar to that of a branching organization. 

In the concurrent processing axperimen*t programmers 
were asked t5 make either data-structure or control-flow 
modifications to each of three programs. For both types of 
modifications, the resource diagrams proved to be the bes: 
performers. The Petri net gave the poorest performance. 

Since the resource diagrams emphasize information 
about the resource-sharing aspect of the processing of ths 
Brageem, ı. iS intezesting to notes that the control-f£low 
information that was so important Tor the sequential 
processing of a program is not as vital for the maintenance 
ef concurrent processes. 

When asked to select the documentation formar that 
wes easiest دخ‎ use, the PDL format was selectad. It c uriel 
out, however, *+hat the nost efficiənt form of dəcumentation 
for tke concurrent processing was the resource diagram. 


Be DISCUSSION 


The results of the experiments yield some ideas that can 
Be incorporated inte explicit documentation types for 
program documentation. هوه هه هل‎ =acorporation of "tie 
ideas,  understandability can be enhanced for maintainers 
resulting in a „positive influence on maintenance 
efficiency. 

When determining the type of documentation to be 
accessed in the documentation hierarchy of Figure 4.1 in 
ete: TII, it is Wportant to realize that there is not 
one "best" form of dccumentation for all maintenance tasks. 
The type of processing (sequential or concurrent) must be 
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Hen ¿into account when identifying the best documentation 
۶939903 tc include in the hierarchy. this pvocesszng infor- 
mation is provided in a narrative sense in level 3. Level 4 
1۱۱١۱ 1137106 the actual flow inforaation, be it resource- 
mow OL CONtESL-flow information. 

The General Electric studies show support for +he 
concept of Minimal documentation introduced in chapter If. 
The English narratives were found t5 bs too long and awkward 
for the test performance of maintenance. When the method of 
transferring information took on the more abbreviated form 
of the PDL, maintainers showed a preference for this format 
of symbology presentaticn. This preference held true for 
bota ths sequential and the concurrent programming techni- 
ques. The implication is “hat, sven though the ideas 
conveyed in both the formal English narrative and the PDL 
were the same, the programmers chose the succinct method of 
symbology as being easier to glaan the necessary informée- 
tion for the maintenance task. ansi gai lcan: Point is that 
the programmers chose not tc wade through all the super- 
fluous language provided by the English narrativs, thus 
Eudewcat2ng a preference for minimal documentation. As far 
as sequential processing is concerned, the PDL proved to 
be not only the programmer!s choice for Symbology represen- 
tection, it also proved to be the most efficient. In the 
case of the concurrent processing, ths PDL was the preferred 
method cf symbolcgy representation, but the resource diagram 
proved to be more efficient. 

The concept of minimal documentation is not centradicted 
by the fact that the PDL form of symbology was preferred by 
programmers, but resource diagrams proved to be the most 
efficient for maintenance purposes in concurrent progran- 
Ming. The fact is that the information required for concur- 
rent processing maintenance is simply different than the 


information that is provided by the PDL. Concurrent 


D 








processin requires information with  emphesis Gum p 


resource-shering aspect sf the progran, while the PDL 
provides information primarily concerning the aspect of 
ccntrol-ilow (which is of primary concern in tha sequertial 
processing program). In this experiment it turned ou* that 
tha actual minimal documentation was the resource diagran, 


and not the PDL the maintainers preferred. 

When determining which format of documentation *o access 
for the performance of maintenance, the format which best 
suits the task at hand should be considered in the selection 
process witn emphasis on maintenance efficisncy. When th2 
proper level (or levels) of documantatior are selected from 
mie documentation hierarchy, along with tha best physical 
representation of the documentation, then mininal documenta- 
tior is accessed and effective understandability is 
achieved. The and result is an effective and efficient 
perfcrnance of the maintenance task. 
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ince maintenance costs makes up the largest part of most 
e ጋ 


5 
tWar 


Ft 


so CES, it is vyital to find effective Ways to 
reduce cr make more efficient the software maintenance 
effort. When good documentation techniques are ínccrporatad 
into th2 preject evolution, then development ideas and othar 
rslevart information about the system can be successfully 
Son ded and transferred tə other individuals. 

ce es critical that good documentation techniques 
be smphasized, accurately determining the precise type and 
geoun. OL ‚Eoeumentatıon for software maintenance is vital. 
Minimal documentation is the result of that determination 
and should, therefore, be incorporated into software 
projects wher2 appropriate. (5685 programs are simply not 
Maintained and therefore do not need maintenance oriented 
documentaticn.) 

Managers of the maintenance team often have misconcep- 
tions about how the time spent on software maintenance 
Should be allocated. Because of these misconceptions, a 
closer look at how maintenance time is spent is in order. 
Perhaps an analysis of the maintenance effort on each 
project should be conducted so as to determine how the main- 
tenance time is actually spent. Ihe manager can then have 
an effective tool with which to schedule the maintenance 
effort without having to resort exclusively to the use of 
0۶۰0 3. 

Programmers should be trained not only to document the 
system as it develops, but to do so keeping the maintenance 
aspect in mind. Maintenance enhanzing documentation should 
be developed simultaneously with the project as an integral 


part cf the system. 





۶۰٥و‎ >6 11060۰. must become aware or the fact that there is 
بت۰۰‎ "DESL" formak or documentation for all =y0=s of 
maintenance. More research like the General FBleccric 


studies should be conducted in ordsr to determine the best 
documentation fcrmat for the particular mainte 
being performed. A particular format, then, should not b 
۳۰٠٠٦٦٦ 5ذ‎ the only prcper way to document a program. 

Well trained programmers will also raise the skill level 
Of the maintenance team, and as skill level increases, the 
need for detailed explicit documentation decreases. The 
skilled programmer can than accept larger conceptual ideas 
about the program, thus avoiding tha need to search through 
a large volume cf information in order to perform the task 
a+ hand. Maintenance and cost efficiercies ars therefore 
enhanced. 

Sincé programmers have more confidence in internal docu- 
Mentation, it is recommended that, to the extent feasible, 
information be carried internally along with the source 
code. As "hard" copies are needed, they could simply be 
printed cut for a specific use. Psrhaps a physical copy of 
poscdocuNen-tatzon should be filed for back up purposes, but 
“he amount of external copies should be kept to a minimum in 
order to avoid the reluctance to keep the hard copies 
updated. In all cases, however, all forms of documentation 
should be updated as modifications to the software are made 
in order to ensure that the docunsntation is an accurate 
n lection Of the project. 

In support of achieving minimal documentation, the 
internally stored documentation should be organized in the 
format of a documentation hierarchy. There should be one 
رج چ۲‎ Structure that will contain all types of explicit 
documentation, and each physical format will be classified 
and filed according to the level of detail contained in the 


document. This "level of detail" tyoe of categorization will 
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necessarily cause the documentation to become a part of 
either the system or the program documentation. 

Users, managers, and maintainers should be abis +0 
access the appropriate piece of documentation based on the 
amount of detail needed for the particular task at hand. 
The system should be set up ín such a way that each level i 


(a 


easily accessed, and a method of moving uv or down the hier- 
archical organization should be made available. 

It ais recommended that further research be conducted 
into the implamentaticn of the hierarchical scheme in a menu 
driven window format that can display the indicated piece of 
documentation on a display screen for perusal. ለ BONG. 
device can point to a place on the menu to request a partic- 
Mirae  p2vel in the hierarchy. The capability to transcend to 
different levels will be built into the menu operation of 
the windows. This documentation hierarchy implementation 
will provide 2 powerful documentation tool that promotes the 
minimal documentation concept, and should result in an effi- 


een maintenance effort. 
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